package buxter.api.commons.signature;

import buxter.api.commons.ApiException;


/**
 * Interface to handle various request signature generation and validation.
 * 
 * @author thijs.reus
 * @author andrei.martchouk
 * @author matthias.gall
 * @author natasha.martchouk
 *
 */
public interface IRequestSignatureHandler {

	/** The Separator for concatenating parameter values */
	public static final String SEPARATOR = "#";
	
	/**
	 * Creates a signature for the given request.
	 * 
	 * @param apiConfigurationId ID of the requester's API configuration
	 * @param requestName name of the request
	 * @param concatenated significant parameter values, using {@link #SEPARATOR}
	 * @return generated signature
	 * @throws AuthenticationFailedException if the signature could not be created
	 */
	String createSignature(String requestName, String parameterValues) throws ApiException;
	
	/**
	 * @param apiConfigurationId ID of the requester's API configuration
	 * @param requestName name of the request
	 * @param concatenated significant parameter values, using {@link #SEPARATOR}
	 * @param signature signature to be validated
	 * @return <code>true</code> iff the given signature is valid,
	 *   <code>false</code> if not
	 * @throws AuthenticationFailedException if the signature could not be validated correctly
	 */
	boolean validateSignature(String requestName, String parameterValues, String signature) throws ApiException;
	
	/**
	 * Concatenates the given elements using {@link #SEPARATOR}. If an element is null,
	 * an empty string is used.
	 * 
	 * @param parameterValues
	 * @return
	 */
	String concatenate(Object... parameterValues);
	
	public String getSharedSecret();

	public void setSharedSecret(String sharedSecret);
	
	public String getApiConfigurationId();

	public void setApiConfigurationId(String apiConfigurationId);
}
